Declarative CSS Modules by KurtCattiSchmidt · Pull Request #11687 · whatwg/html

KurtCattiSchmidt · 2025-09-24T00:00:42Z

Adds support for Declarative CSS Modules via <style type="module" specifier="specifiername">. shadowrootadoptedstylesheets is handled in this PR: #12339

At least two implementers are interested (and none opposed):
- Chromium
- …
Tests are written and can be reviewed and commented upon at:
- wpt/html/semantics/document-metadata/the-style-element/tentative (see https://wpt.fyi/results/html/semantics/document-metadata/the-style-element/tentative)
Implementation bugs are filed:
- Chromium: https://issues.chromium.org/issues/448174611
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=2037650
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=314242
- Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): N/A
- Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): N/A
Corresponding HTML AAM & ARIA in HTML issues & PRs: N/A
MDN issue is filed: Declarative CSS Module Scripts mdn/mdn#824
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

Addresses #10673

/acknowledgements.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/obsolete.html ( diff )
/scripting.html ( diff )
/semantics.html ( diff )

Copilot

Pull Request Overview

This PR introduces declarative CSS modules support to HTML, allowing CSS to be imported as modules through <style> elements with a specifier attribute and <template> elements with a shadowrootadoptedstylesheets attribute.

Adds a specifier attribute to <style> elements that creates module import maps for CSS content
Introduces a shadowrootadoptedstylesheets attribute for <template> elements to declaratively adopt CSS modules
Implements algorithms for creating declarative CSS module scripts and stylesheet adoption

Comments suppressed due to low confidence (5)

source:1

Missing attribute name in IDL definition. Should be [SameObject, PutForwards=value, Reflect] readonly attribute DOMString <dfn attribute for="HTMLStyleElement" data-x="dom-style-specifier">specifier</dfn>; to match the pattern used for other attributes in this interface.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Grammar error: 'is defines' should be 'defines' - remove the word 'is'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Grammar error: 'appended with the of the' should be 'appended with the' - remove the duplicate 'the of'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Logic error: The algorithm references <var>specifier</var> but this variable is not defined in the algorithm. It should reference the value of the shadowrootadoptedstylesheets attribute instead.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference: Should be data-x=\"attr-style-specifier\" not data-x=\"attr-style-blocking\" for the specifier attribute row.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (9)

source:1

The IDL attribute should be named to match the content attribute. The content attribute is specifier but the IDL should use camelCase convention: [SameObject, PutForwards=value, Reflect] readonly attribute DOMString specifier; should have a data-x attribute defining the DOM property name.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The algorithm step is missing proper HTML structure. It should end with </li> and the nested <ol> should be properly closed with </ol>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

The variable moduleScript is referenced but never defined in this algorithm. This should likely be the current module script or settings object context.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

These variable assignments are missing closing </p> tags. Each should end with </p></li>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Missing spaces after commas in the parameter list. Should be <var>fetchClient</var>, <var>destination</var>, <var>options</var>, <var>settingsObject</var>, <var>referrer</var> for consistency.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference in the table. Line 148289 should reference data-x=\"element-template\" or similar, not data-x=\"attr-template-shadowrootclonable\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

Incorrect data-x reference in the table. Line 148363 should reference data-x=\"element-style\" instead of data-x=\"attr-style-blocking\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

…able

dandclark

Review in progress, sharing feedback so far.

mhochk

LGTM (No permissions to actually Approve)

dandclark

This is coming together nicely. I think the biggest thing still to figure out is to prevent a given <style type=module> from being processed twice. I'm about to head out on leave so I'm going to Approve this since I'm supportive of the direction and I trust that the remaining open issues will be handled appropriately.

dandclark · 2025-10-07T23:21:46Z

+  <ol>
+   <li><p>Let <var>element</var> be the <code>style</code> element.</p></li>
+
+   <li><p>If <var>element</var> is not <span>connected</span>, then return.</p></li>


I guess this is also the point where we'd also check a new equivalent of the already started flag to ensure a given <style type=module> only ever gets processed once?

Yeah I'll have to think about this a little more. I will likely bring this up soon with the WHATWG.

It doesn't seem like this got addressed one way or another?

dandclark · 2025-10-07T23:27:51Z

+   of the value of the <span data-x="attr-style-specifier">specifier attribute</span> and a value of
+   <var>styleDataURI</var>.</p></li>
+
+   <li><p><span>Create an import map parse result</span> with <var>input</var> as <var>jsonString</var>


Create an import map parse result can throw -- do we need to handle any of those cases? The one I particularly had in mind to watch for is does it throw when a given specifier is invalid? If not, do we need to handle an invalid specifier some other way?

Good question. For now I added a step to look at the importMapParseResult's error to rethrow and to continue if that happens. In practice, we probably want to log something in the console, but this might be enough for the spec.

zcorpan · 2025-10-09T16:57:52Z

You can include "Fixes #10673" in the OP so that there's a link from the issue in GitHub's UI. (Also should be in the commit message when squashing.)

KurtCattiSchmidt · 2025-10-09T23:43:01Z

@annevk - I believe the last two commits addressed all of the issues you brought up this morning, so please take a look when you get a chance. And also let me know if I missed anything else you mentioned today.

annevk · 2025-10-13T05:19:27Z

I think the most substantive issue I raised was not addressed: #10673 (comment). I think we either need something like blob: URLs or allow the module map to contain element references. Not sure.

KurtCattiSchmidt · 2025-10-20T16:49:34Z

I think the most substantive issue I raised was not addressed: #10673 (comment). I think we either need something like blob: URLs or allow the module map to contain element references. Not sure.

@annevk - I just pushed an update that switches the dataURI to a Blob URI. I think this approach is much simpler than expanding the module map to contain element references.

I've been thinking about the Blob approach and haven't come up with any major reasons not to go this route. The lifetime of the Blob object is an interesting one, and it would be nice to give developers a way to revoke the Blob URL. I don't think removing the <style> tag is a good method anymore though, because you would expect that re-inserting it would re-activate it and Blob URL's cannot be reactivated after revoking them. So maybe exposing the Blob URL somewhere is a better option.

KurtCattiSchmidt · 2026-02-26T17:11:32Z

@keithamus - here is the split PR with just the declarative modules

noamr · 2026-03-12T16:17:06Z

I still think that we can have declarative CSS modules with URLs before we go down the rabbit hole of supporting them in inline styles with something like specifier.

The main issue with re-importing CSS URLs in shadow DOM is that they are duplicate.
We can support de-duping them in module-style regardless of supporting them in inline styles, e.g.:

<script type=importmap>
  { "mytheme": { type: "css", href: "theme.css" } }
</script>
<my-element>
  <template shadowrootadoptedstylesheets="mytheme">...</theme>
</my-element>

Or something like:

<script type=importmap>
  { "mytheme": { type: "css", href: "theme.css" } }
</script>
<my-element>
  <link rel=stylesheetmodule href="theme.css">
  <!-- or -->
  <link rel=stylesheetmodule href="mytheme">
</my-element>

This decouples the issue of deduping stylesheet references from the issue of importing inline styles.
The former is a stylesheet-specific problem and the latter, while valid, relates to script modules as well, while this proposal is stylesheet specific.

KurtCattiSchmidt · 2026-03-26T00:56:36Z

I still think that we can have declarative CSS modules with URLs before we go down the rabbit hole of supporting them in inline styles with something like specifier.

Thanks @noamr. I've recently split the URL version into its own explainer, see https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOMAdoptedStyleSheets/explainer.md.

The main issue with re-importing CSS URLs in shadow DOM is that they are duplicate. We can support de-duping them in module-style regardless of supporting them in inline styles, e.g.:
...
This decouples the issue of deduping stylesheet references from the issue of importing inline styles. The former is a stylesheet-specific problem and the latter, while valid, relates to script modules as well, while this proposal is stylesheet specific.

This proposal creates an import map entry under-the-hood for the specifier attribute on <style>, mapping to a generated Blob URL so there's no duplication involved for a given specifier. This approach could easily be expanded to <script> for script and JSON modules. There's nothing in this proposal that needs to be limited to stylesheets. Happy to chat about this at the sync tomorrow of you're available.

annevk

This still looks far from ready to me. I'm also wondering if we have a good story as to how we eventually want to make this consistent with the script element. Will that get a specifier attribute too?

annevk · 2026-05-10T06:47:37Z

  attribute boolean <span data-x="dom-style-disabled">disabled</span>;
  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLStyleElement" data-x="dom-style-media">media</dfn>;
  [SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>, <span data-x="xattr-Reflect">Reflect</span>] readonly attribute <span>DOMTokenList</span> <dfn attribute for="HTMLStyleElement" data-x="dom-style-blocking">blocking</dfn>;
+  [SameObject, PutForwards=value, Reflect] readonly attribute DOMString specifier;


This doesn't make sense.

annevk · 2026-05-10T06:48:54Z

+
+  <ul>
+   <li><p>The element is popped off the <span>stack of open elements</span> of an <span>HTML
+   parser</span> or <span>XML parser</span>.</p></li>


Is this just a subset of the next condition?

annevk · 2026-05-10T06:52:09Z

+   <code data-x="dom-Blob-type">type</code> of "<code>text/css</code>".</p></li>

+   <li><p>Let <var>styleBlobURL</var> be the <span data-x="concept-url-blob-entry">blob URL entry</span>
+   associated with <var>styleBlob</var>.</p></li>


This is not how this works. A Blob isn't automatically in a store and concept-url-blob-entry doesn't belong to Blob objects either. (Also, a blob URL entry is a struct, not a URL.)

annevk · 2026-05-10T06:53:56Z

+   <var>styleBlobURL</var>.</p></li>
+
+   <li><p>Let <var>jsonString</var> be the result of calling <span>JSON.stringify</span> on
+   <var>jsonObject</var>.</p></li>


This is wrong. We should be using Infra primitives for JSON.

annevk · 2026-05-10T06:56:23Z

+  <p>Authors should not specify a value for the <code data-x="attr-style-type">type</code>
+  attribute on <code>style</code> elements, if that value is an <span>ASCII case-insensitive</span>
+  match for "<code>text/css</code>". Instead, they should omit the attribute, which has the same
+  effect.</p>


This is wrong. Now we're no longer stating what the attribute must contain.

annevk · 2026-05-10T06:59:16Z

+  <ol>
+   <li><p>Let <var>element</var> be the <code>style</code> element.</p></li>
+
+   <li><p>If <var>element</var> is not <span>connected</span>, then return.</p></li>


It doesn't seem like this got addressed one way or another?

annevk · 2026-05-10T07:02:54Z

+   with <var>input</var> as <var>jsonString</var> and <var>baseURL</var> as the <span>document base URL</span>.</p></li>
+
+   <li><p>If <var>importMapParseResult</var>'s <span data-x="impr-error-to-rethrow">error to rethrow</span> is
+   not null, then return.</p></li>


Why would we silently eat exceptions? Can't we let register an import map surface them?

noamr · 2026-05-11T15:26:34Z

I think that the main issue with this solution, beyond it being tailor-made for styles and ignored for scripts, is that "shadow roots are able to export styles directly to the import map" using an attribute is exotic, as in inconsistent with both how shadow roots work and with how the import map work.

Usually shadow roots should not be able to implicitly affect what's outside of them, and this changes that: any shadow root can import something from a specifier and any shadow root can populate the style that corresponds to that specifier.

I understand the performance-driven use case for this (sharing styles between custom elements that are nested deep in the DOM without duplicating them) but I think we need to find a design that's less radical in terms of breaking shadow DOM encapsulation.

A solution I've brought up before for this was being able to somehow share a style based on an integrity digest, which guarantees that the key and values have some relationship between them, or alternatively having some sort of namespace for CSS modules that is overridable from inside shadow-roots (kind of like data- attributes).

Initial commit

7f91f78

KurtCattiSchmidt requested a review from Copilot September 24, 2025 00:00

Copilot AI reviewed Sep 24, 2025

View reviewed changes

mhochk reviewed Sep 24, 2025

View reviewed changes

Comment thread source Outdated

Comment thread source

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

KurtCattiSchmidt added 2 commits September 24, 2025 14:39

Adding missing shadowrootadoptedstylesheets and other small fixes

b8c96ae

Addressing Hoch's feedback

4487b30

KurtCattiSchmidt requested a review from Copilot September 24, 2025 21:54

Copilot AI reviewed Sep 24, 2025

View reviewed changes

Fixing order and removing duplicate shadowrootadoptedstylesheets

fde2e28

KurtCattiSchmidt mentioned this pull request Sep 24, 2025

Upcoming WHATNOT meeting on 2025-09-25 #11696

Closed

KurtCattiSchmidt added 5 commits September 25, 2025 16:21

Fixing shadowrootadoptedstylesheets to definition to not include clon…

141c474

…able

Wrapping algorithm per new requirements

c174820

Fixing formatting

477caa7

Merge branch 'main' into css-modules-firstpr

582566e

Fixing <li> conformance error

ccac8fe

KurtCattiSchmidt requested review from dandclark and domenic September 26, 2025 23:35

KurtCattiSchmidt added 3 commits September 29, 2025 11:46

Simplifying stylesheet adopting steps

746cdad

Making stylesheet adopting steps append instead of set

ca450c7

Fixing typo

d8cae13

KurtCattiSchmidt requested a review from smaug---- September 30, 2025 16:42

KurtCattiSchmidt mentioned this pull request Sep 30, 2025

Declarative CSS Modules and Declarative Shadow DOM adoptedstylesheets attribute #10673

Open

KurtCattiSchmidt removed the request for review from domenic September 30, 2025 16:51

dandclark reviewed Oct 2, 2025

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

KurtCattiSchmidt added 2 commits October 6, 2025 13:40

Addressing Dan's feedback

11fcb56

Minor style fixes

9e2f7ee

KurtCattiSchmidt requested review from dandclark and mhochk October 6, 2025 21:16

mhochk reviewed Oct 6, 2025

View reviewed changes

dandclark approved these changes Oct 8, 2025

View reviewed changes

Addressing Dan's second round of feedback

b2c6025

zcorpan reviewed Oct 9, 2025

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

KurtCattiSchmidt added 3 commits October 9, 2025 16:00

Updating external URL references to draft URL's

adf1484

Adding component percent-encode set per Anne's feedback

05edbed

Separating JSON string step into a JSON object + stringify

6cee43f

KurtCattiSchmidt requested a review from annevk October 9, 2025 23:41

Updating wording on the 'type' attribute being obselete

6a95872

Converting Import Map to Blob

188162a

KurtCattiSchmidt added 2 commits February 20, 2026 14:09

Removing shadowrootadoptedstylesheets for now

e9fb25a

Minor cleanups

3992d68

mhochk reviewed Feb 21, 2026

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

Wording tweaks

9bf97b2

KurtCattiSchmidt requested a review from keithamus March 3, 2026 17:36

KurtCattiSchmidt added the agenda+ To be discussed at a triage meeting label Mar 11, 2026

KurtCattiSchmidt mentioned this pull request Mar 30, 2026

Upcoming WHATNOT meeting on 2026-04-02 #12322

Closed

cwilso removed the agenda+ To be discussed at a triage meeting label Apr 7, 2026

This was referenced May 6, 2026

shadowrootadoptedstylesheets on <template> #12339

Open

Upcoming WHATNOT meeting on 2026-05-07 #12413

Closed

zeroedin mentioned this pull request May 8, 2026

poc: CSS Modules using shadowrootadoptedstylesheets for the Lit SSR pipeline RedHat-UX/red-hat-design-system#3012

Open

7 tasks

annevk reviewed May 10, 2026

View reviewed changes

Conversation

KurtCattiSchmidt commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mhochk left a comment

Choose a reason for hiding this comment

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zcorpan commented Oct 9, 2025

Uh oh!

KurtCattiSchmidt commented Oct 9, 2025

Uh oh!

annevk commented Oct 13, 2025

Uh oh!

KurtCattiSchmidt commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

KurtCattiSchmidt commented Feb 26, 2026

Uh oh!

noamr commented Mar 12, 2026

Uh oh!

KurtCattiSchmidt commented Mar 26, 2026

Uh oh!

annevk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KurtCattiSchmidt commented Sep 24, 2025 •

edited

Loading